Web/Security reorganization

[wbamberg]

This post is to propose a new organization for the docs under Web/Security. There is more stuff we might end up with there, but this is the initial set.

• Threat modelling for developers

  A single page that outlines in practical terms the kinds of things a website might be doing that make it a potential target for specific sorts of attacks. For example: if you have signed-in users, and use cookies to authorize state-changing requests (for instance form a form) then you're potentially a target for CSRF attacks.

• Fundamental security practices checklist

  A single page that lists the basic things a developer should consider doing, to secure their site. Things like: using HTTPS, setting sensible cookie attributes, restricting framing. This would point to separate docs, mostly under "Defenses", for more detail.

• Theory

  A directory of pages, each of which describes some theoretical aspect of web security. These pages don't generally map to anything particular a developer is going to do, but are background conceptual knowledge that they need. The canonical page is the one on same-origin policy, but the current pages on TLS and secure contexts might also fit there. These are what Diataxis calls Explanation.

• Attacks

  A directory of pages, each outlining a type of attack that a website might be vulnerable to. This section would include things like: XSS, CSRF, Clickjacking. Each of these pages is split into two sections, the first describing the attack and the second describing defenses. Most of this is in place: https://developer.mozilla.org/en-US/docs/Web/Security/Attacks. From a Diataxis point of view, these are a bit more like How-to guides, but are probably more conceptual and high-level than most how-tos. So they're a bit of a blend between Explanation and How-to.

• Defenses

  A directory of pages, each outlining a defense. This section would include things like: using HTTPS, using fetch metadata, setting SameSite, SRI, framing protection. I wasn't originally planning to have this, but as I've worked through the attacks it's clear that there's a many-many relationship between attacks and defenses - for example, framing protection is a defense against several attacks. So I'm getting quite a bit of duplication in the "defenses" section of the "attacks" doc. So it might be better to document defenses standalone, and then point there from "attacks".

  One question: why are some things, like "Using fetch metadata", here under Defenses, and others, like "Using CSP", under HTTP? I don't have a good answer to this.

Another question is, what happens to the existing pages under Web/Security? I'll deal with this in a follow up.

[pransh15]

Hi @wbamberg, thanks for submitting this proposal. I like this idea, let's see what everyone has to say. I'll share it with the team to see if they have any thoughts they would like to share here.